STM32Cube Embedded Software Context

Purpose and scope

The STM32Cube Embedded Software (eSW) Context provides example discovery, source analysis, validated HAL2/LL guidance, Python environment checks, and application-code assistance.

In bundle and command names, esw stands for embedded software.

The agent can also write or change application code using HAL2/LL, grounded in the project’s sources, selected examples, and available guidance. This is not a standalone chatbot or a replacement for the Build, Debug, Programmer, or STM32CubeMX2 contexts. Ask for clarification when source evidence is insufficient. HAL/LL guidance currently covers STM32C5.

Example discovery checks whether a candidate covers the requested combination of peripherals. Example and guidance workflows do not change a project. Application-code workflows can change the selected project files. HAL1-to-HAL2 project migration is not delivered in this release.

Context scope

The installed eSW 1.0.0 service catalog uses these identifiers. Identifiers belong to this context and can differ between bundle versions:

Embedded-software service selection

ID

Service

Purpose

S0

esw.environment-setup

Required Python environment checks and preparation.

S1

esw.examples-explorer

Example discovery and selected-source analysis.

S2

esw.hal-ll-guidance

Documented HAL2/LL usage, API reference, and runtime guidance.

S5

esw.application-code

Write, change, or complete application code using HAL2/LL.

Run cube cube-agentic-ai-esw --list-ai-services to inspect the catalog provided by the installed version before choosing services interactively.

  • Find and compare examples by series, board, peripheral, or search terms. Retrieve a selected README and inspect explicitly selected source files.

  • Get HAL2/LL documented usage, API reference, and runtime guidance from validated ST documentation.

  • Write or change application code using HAL2/LL, grounded in the selected project’s sources, examples, and available guidance.

Assets and capabilities

The context is delivered in the cube-agentic-ai-esw bundle. Python 3.10 or later is required for HAL/LL guidance. The toolkit does not install Python. Install it from the Python downloads page or use an existing Python executable.

Python setup

For a new project, setup supports --python auto (the default), --python venv, or --python "<absolute executable path>". The installation guide uses venv for an isolated environment. The choice is recorded per project and eSW version, and doctor --fix reuses it.

If a selected service declares additional Python packages, the installer installs them when their declared version ranges are not met. It does not upgrade a compatible installed version. For interpreter detection, package repair, proxy configuration, and shared-environment maintenance, see How can I diagnose eSW Python setup?.

Network access

Example searches use the bundled catalog and do not require network access. Retrieving selected source files from GitHub requires network access and approval. HAL/LL guidance retrieves public ST documentation over HTTPS and caches successful responses locally for a limited time. Python package installation needs access to the configured package index or approved mirror.

Cube commands

The bundle command provides example operations:

:header: “Command”, “Use” :widths: 55, 45

cube cube-agentic-ai-esw --examples-query

Search the example database. Use filters such as --search, --series, or --board.

cube cube-agentic-ai-esw --list-ai-services

List service identifiers, names, and descriptions for this installed version.

cube cube-agentic-ai-esw --examples-readme

Retrieve the README for a selected example.

cube cube-agentic-ai-esw --examples-materialize

Materialize explicitly named source files for analysis.

cube cube-agentic-ai-esw --examples-navigate

Navigate a selected local source projection.

cube cube-agentic-ai-esw --examples-inspect

Inspect a selected source file or projection.

cube cube-agentic-ai-esw --examples-inventory

List supported example series, boards, and peripherals.

cube agentic-ai setup --python <auto|venv|path>

Choose the Python used for eSW HAL/LL guidance in a new project.

cube agentic-ai doctor <project> --fix

Check and resolve declared dependencies for an existing project.

HAL/LL guidance uses a supervised lookup: 

cube cube-agentic-ai-esw --run-with-feedback -- cube cube-agentic-ai-esw --hal-lookup <command> --target <target> --peripheral <PERIPHERAL>

Run cube cube-agentic-ai-esw --help for command arguments.

Typical prompts

  • Find a STM32Cube UART example for this board and explain why it matches.

  • Show the README and initialization files for the closest SPI example.

  • Compare the source files in these two STM32Cube examples.

  • Find an example that uses DMA with this peripheral and cite the source files.

  • Explain the HAL2 initialization sequence for this peripheral.

  • Explain when this HAL2 API reports transfer completion and what its errors mean.

  • Add a DMA-based UART transmit path to this HAL2 project, following the closest example and checking for resource conflicts.